KML and Google Earth Features

KML Reflector

WMS Convenience Wrapper for KML

Overview

Standard WMS requests can be quite long and verbose. For instance like the following:

http://localhost:8080/geoserver/wms?service=WMS&request=GetMap&version=1.1.1&format=application/vnd.google-earth.kml+XML&width=1024&height=1024&srs=EPSG:4326&layers=topp:states&styles=population&bbox=-180,-90,180,90

Typing into a browser can be quite cumbersome and error prone. Not to mention repetitive as many of the parameters do not change. The KML Reflector solves this problem nicely. The reflector concept involves filling in sensible defaults for many of the paramaters of a standard WMS request so the user does not have to. Using the reflector one can shorten the above request to:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states

Using the KML Reflector

To use the KML reflector all one must do is specify wms/kml_reflect? as opposed to wms? in a request. The only mandatory parameter to a kml reflector call is the layers parameter. As stated above the reflector fills in sensible defaults for the rest of the parameters. The following table lists all the defaults used:

The styles parameter is derived by using the default style as configured by GeoServer for each layer specified in the layers parameter.

Any of these defaults can be overridden when specifying the request. For instance if one wanted to specify a particular style to be used:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&styles=population

Or to specify a particular bounding box:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&bbox=-124.73,24.96,-66.97,49.37

Custom Descriptions

Controlling the description element (balloon pop-up) of your KML

Overview

When GeoServer generates KML for a vector dataset, it attaches information from the data to each Placemark that is created. By default this is a simple HTML table which displays all the attribute data (metadata in KML terms).

In some cases this is not ideal. For instance if some of the attributes of the dataset are sensitive and not to be made public. In this case it is possible to use the KMATTR parameter in a KML request to turn off attribution.

Specifying KMATTR

Specifying KMATTR in a request easy.. All one must do is append the parameter "kmattr=<true|false>" to a KML request. For example:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states*kmattr=false

Attribution with Templates

An alternative to simply turning attribution off is use a template to customize which attributes are attached to a Placemark. Applying templates to KML Placemarks is described in detail here. There is also an in depth tutorial that hits on many of the powerful things one can do.

Scoring

Introduction

GeoServer can return KML in one of two forms. The first is as a number of Placemark elements. Each Placemark corresponds to a feature in the underlying dataset. This form only applies to vector datasets.

The second form is as an Overlay element. In this form the rendering is done by the GeoServer WMS and only the resulting image is sent to Google Earth. This is the only form available for raster datasets, but can be applied to vector datasets as well.

Both forms are available for vector datasets, which one is used is driven by the size of the dataset. The first (Placemark) form looks nicer but if the dataset is large then the amount of data can cause Google Earth to hang trying to process it all. Having GeoServer render as an Overlay puts less of a strain on Google Earth, but unfortunately does not look as good.

The following shows the same dataset rendered in Placemark form on the left and Overlay form on the right.

KML Scoring

Luckily the user usually does not have to worry about this. GeoServer is smart enough to figure out which form should be used on its own based on the amount of data that is being queried. A threshold value is used for which if the number of features returned is greater then a certain value then the Overlay form is used. Determining this threshold value is called KML Scoring.

By default, GeoServer will use Overlay form if more then 2154 features are being returned to Google Earth. However this value can be controlled by the user via the KMSCORE parameter. The KMSCORE parameter is specified as part of a KML request and is an integer value between 0 and 100. The default value for this parameter is 50. If you have a high powered computer you can likely set this higher and get back more vector data.

GeoServer uses the following formula to calculate the feature threshold value:

number of features = 10^(KMSCORE/15)

The following shows the values of the feature threshold for different values of the KMSORE parameter:

KMSCORE Number of Features 0 Always Raster 10 4 20 21 30 100 40 464 50 2154 60 10000 70 46415 80 215443 90 1000000 99 3981071 100 Always Vector

Specifying KMSCORE

Specifying KMSCORE in a request easy.. All one must do is append the parameter "kmscore=<value>" to a KML request. For example:

http://localhost:8080/geoserver/wms/kml_reflecet?layers=topp:states&kmscore=20

Legend Overlays

KML Legend Overlays

Overview

One of the operations of WMS is GetLegendGraphic which allows a WMS client to obtain a legend graphic from the server for a particular layer. Combining it with KML overlays produces a nice way to produce legends in Google Earth.

Using Legend Overlays

Getting GeoServer to return KML with a legend overlay is easy. All one must do is append the parameter "legend=true" to a KML request. For example:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&legend=true

Google Earth aggressively caches overlays. Which means if you change a style in GeoServer expecting it to impact the look of your legend overlay chances are it will not until you restart Google Earth.

Super-Overlays

Overview

Super-Overlays are a form of KML in which data is broken up into regions. This allows Google Earth to refresh/request only particular sections of the map when the view area changes. Super overlays are used to efficiently publish large sets of imagery.

With super overlays, regions or tiles form a hierarchy. Each level of the hierarchy corresponds to a particular image resolution. Tiles that are lower in the hierarchy correspond to higher resolution. This allows Google Earth to progressively load higher resolution imagery as a user zooms in on the map.

GeoServer takes all the pain out of Super-Overlay creation, as it automatically creates the proper hierarchy and tiles the data. The only thing to be done is to add your data to GeoServer. It can tile vector data, but it truly shines with large raster data (GeoTiff, ArcGrid, GTOPO30, ImageFiles, and soon MrSID).

Consider the above tile which is at some level n of our hierarchy. As we zoom in we see higher resolution tiles for the next level n+1 are loaded.

Using Super Overlays

Getting GeoServer to return KML as a super overlay is easy. All one must do is append the parameter "superoverlay=true" to a KML request. For example:

http://localhost:8080/geoserver/wms/kml_reflect?layers=nurc:Img_Sample&superoverlay=true

In the current version we don't have a good 'lookAt' value, so Google Earth zooms you out. So you have to know where your layer is and zoom back in. In the future we hope to improve that.

Super Overlays and Tiling

GeoServer implements super overlays in a way that is compatible with the WMS Tiling Client Recommendation. Super overlays are generated in such a way that the regions of tiles of the super overlay are the same tiles that a WMS tiling client would request. The upshot of this is that one can use existing tile caching mechanisms and reap a potentially large performance benefit.

This tutorial walks through the process of setting up super overlays with tile caching.

Under Development Super overlays are still under active development. Please try it out and report any bugs in the issue tracker

Time Visualization

Overview

One of the slickest features of Google Earth is the time slider, which allows you to visualize changes in a dataset over time. As of version 1.5.2 GeoServer makes it very simple to convert existing geospatial data that has a time element in to Google Earth.

Using Time with GeoServer

To use time with GeoServer you need a dataset that has a time or date as one of the elements. To use it in GeoServer you make a 'template' file called time.ftl, and place it in the featureTypes directory. GeoServer will then return the proper values to Google Earth, and the time slider will automatically appear. For more information on setting this up, see the Time Template Tutorial.

Filtering Data

Overview

Though not a specific Google Earth feature, GeoServer has a powerful capability to limit the data returned based on a query passed in by the user. The KML Reflector will pass through any 'FILTER' or 'CQL_FILTER" parameter to GeoServer to constrain the response. Filters are basically a translation of a SQL 'WHERE' statement in to web form, and allow the full power of SQL, though limited to a single table. One can do logical filters, like AND and OR, to make very complex queries, leveraging numerical and string comparisons, geometric operations (bbox, touches, intersects, disjoint), LIKE statements, nulls, and more.

OGC Filters

There is an open standard put out by the Open Geospatial COnsortium called 'Filter Encoding' GeoServer implements the full spec, so read it for the full language with examples.

There simplest filter is very easy to include. It is called the 'featureid' filter, and it lets you grab a single feature by saying its id:

This request will take you to the state of Maryland. The featureids of your data are most easily found by doing WFS requests and examining the resulting GML. KML output will also include the featureids if there is not a template that overrides it.

After the basics using Filters in a URL gets a little out of hand, as one is supposed to include a full XML filter inside the url, like:

So we don't recommend using those. Instead there is CQL, which allows one to specify the same long statement much more succinctly.

CQL Filters

See Common Query Language (CQL) Tutorial (unfinished) for an introduction to CQL queries.

For right here we'll just demonstrate what the above query would be in CQL:

Which is much more compact. That query will get you all the states in the US with square kilometers of land between 100,000 and 150,000: